<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>DbEnv::set_thread_id()</title>
    <link rel="stylesheet" href="apiReference.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB C++ API Reference" />
    <link rel="up" href="env.html" title="Chapter 5.  The DbEnv Handle" />
    <link rel="prev" href="envset_thread_count.html" title="DbEnv::set_thread_count()" />
    <link rel="next" href="envset_thread_id_string.html" title="DbEnv::set_thread_id_string()" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">DbEnv::set_thread_id()</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="envset_thread_count.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 5. 
                The DbEnv Handle
        </th>
          <td width="20%" align="right"> <a accesskey="n" href="envset_thread_id_string.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="envset_thread_id"></a>DbEnv::set_thread_id()</h2>
          </div>
        </div>
      </div>
      <pre class="programlisting">#include &lt;db_cxx.h&gt;
 
int
DbEnv::set_thread_id(char *(*thread_id_string)(DbEnv *dbenv,
    pid_t pid, db_threadid_t tid, char *buf));</pre>
      <p>
         Declare a function that returns a unique identifier pair for the
         current thread of control. The <code class="methodname">DbEnv::set_thread_id()</code> method
         supports the <a class="xref" href="envfailchk.html" title="DbEnv::failchk()">DbEnv::failchk()</a>  method. 
         For more information, see 
         <a href="../../programmer_reference/cam_app.html" class="olink">Architecting Data Store and 
         Concurrent Data Store applications</a>, and 
     <a href="../../programmer_reference/transapp_app.html" class="olink">Architecting Transactional Data Store
         applications</a>, both in the
     <em class="citetitle">Berkeley DB Programmer's Reference Guide</em>.
    </p>
      <p>
         The <code class="methodname">DbEnv::set_thread_id()</code> method configures operations performed
         using the specified <a class="link" href="env.html" title="Chapter 5.  The DbEnv Handle">DbEnv</a>  handle, not all
         operations performed on the underlying database environment.
    </p>
      <p>
         The <code class="methodname">DbEnv::set_thread_id()</code> method may be called at any time during
         the life of the application.
    </p>
      <p>
         The <code class="methodname">DbEnv::set_thread_id()</code> <span>
            
            <span>
                method either returns a non-zero error value or throws an
                exception that encapsulates a non-zero error value on
                failure, and returns 0 on success.
            </span>
        </span>
    </p>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="id1674976"></a>Parameters</h3>
            </div>
          </div>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="id1674971"></a>thread_id</h4>
              </div>
            </div>
          </div>
          <p>
                          The <span class="bold"><strong>thread_id</strong></span> parameter is a function
                          which returns a unique identifier pair for a thread of control in a
                          Berkeley DB application.  The function takes three arguments:
                     </p>
          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p>
                                 <span class="bold"><strong>dbenv</strong></span>
                             </p>
                <p>
                                The <span class="bold"><strong>dbenv</strong></span> parameter is the enclosing
                                database environment handle, allowing application access to the
                                application-private fields of that object.
                             </p>
              </li>
              <li>
                <p>
                                 <span class="bold"><strong>pid</strong></span>
                             </p>
                <p>
                                The <span class="bold"><strong>pid</strong></span> points to a memory location of
                                type <code class="literal">pid_t</code>, or NULL.  The process ID of the current
                                thread of control may be returned in this memory location, if it is not
                                NULL.
                            </p>
              </li>
              <li>
                <p>
                                 <span class="bold"><strong>tid</strong></span>
                             </p>
                <p>
                                 The <span class="bold"><strong>tid</strong></span> points to a memory location of
                                 type <code class="literal">db_threadid_t</code>, or NULL.  The thread ID of the
                                 current thread of control may be returned in this memory location, if it
                                 is not NULL.
                             </p>
              </li>
            </ul>
          </div>
        </div>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="id1675167"></a>Errors</h3>
            </div>
          </div>
        </div>
        <p>
                         The <code class="methodname">DbEnv::set_thread_id()</code> <span>
            
            <span>
                method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 
                exception, encapsulating one of the following non-zero errors, or return one
                of the following non-zero errors:
            </span>
        </span>
                    </p>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="id1675331"></a>EINVAL</h4>
              </div>
            </div>
          </div>
          <p>
                An invalid flag value or parameter was specified.
            </p>
        </div>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="id1675337"></a>Assigning Thread IDs</h3>
            </div>
          </div>
        </div>
        <p>
                    The standard system library calls to return process and thread IDs are often sufficient for this
                    purpose (for example, <code class="methodname">getpid()</code> and
                        <code class="methodname">pthread_self()</code> on POSIX systems or GetCurrentThreadID on Windows
                    systems). However, if the Berkeley DB application dynamically creates processes or threads, some
                    care may be necessary in assigning unique IDs. In most threading systems, process and thread IDs are
                    available for re-use as soon as the process or thread exits. If a new process or thread is created
                    between the time of process or thread exit, and the 
                    <a class="xref" href="envfailchk.html" title="DbEnv::failchk()">DbEnv::failchk()</a> method is run, it may be possible for 
                    <a class="xref" href="envfailchk.html" title="DbEnv::failchk()">DbEnv::failchk()</a>                    
                    to not detect that a thread of control exited without properly
                    releasing all Berkeley DB resources.
            </p>
        <p>
                    It may be possible to handle this problem by inhibiting process or thread
                    creation between thread of control exit and calling the 
                    <a class="xref" href="envfailchk.html" title="DbEnv::failchk()">DbEnv::failchk()</a>
                    method.  Alternatively, the <span class="bold"><strong>thread_id</strong></span> function
                    must be constructed to not re-use <span class="bold"><strong>pid/tid</strong></span>
                    pairs. For example, in a single process application, the returned process ID
                    might be used as an incremental counter, with the returned thread ID set to the
                    actual thread ID.  Obviously, the <span class="bold"><strong>is_alive</strong></span>
                    function specified to the 
                    <a class="xref" href="envset_isalive.html" title="DbEnv::set_isalive()">DbEnv::set_isalive()</a> 
                    method must be compatible with any
                    <span class="bold"><strong>thread_id</strong></span> function specified to
                    <code class="methodname">DbEnv::set_thread_id()</code>.
            </p>
        <p>
                    The db_threadid_t type is configured to be the same type as a standard thread identifier, in
                    Berkeley DB configurations where this type is known (for example, systems supporting pthread_t or
                    thread_t, or DWORD on Windows). If the Berkeley DB configuration process is unable to determine the
                    type of a standard thread identifier, the db_thread_t type is set to uintmax_t (or the largest
                    available unsigned integral type, on systems lacking the uintmax_t type). Applications running on
                    systems lacking a detectable standard thread type, and which are also using thread APIs where a
                    thread identifier is not an integral value and so will not fit into the configured db_threadid_t
                    type, must either translate between the db_threadid_t type and the thread identifier (mapping the
                    thread identifier to a unique identifier of the appropriate size), or modify the Berkeley DB sources
                    to use an appropriate db_threadid_t type. Note: we do not currently know of any systems where this
                    is necessary. If your application has to solve this problem, please contact our support group and
                    let us know.
            </p>
        <p>
                    If no <span class="bold"><strong>thread_id</strong></span> function is specified by the
                    application, the Berkeley DB library will identify threads of control by using
                    the <code class="methodname">taskIdSelf()</code> call on VxWorks, the
                    <code class="methodname">getpid()</code> and
                    <code class="methodname">GetCurrentThreadID()</code> calls on Windows, the
                    <code class="methodname">getpid()</code> and <code class="methodname">pthread_self()</code>
                    calls when the Berkeley DB library has been configured for POSIX pthreads or
                    Solaris LWP threads, the <code class="methodname">getpid()</code> and
                    <code class="methodname">thr_self()</code> calls when the Berkeley DB library has been
                    configured for UI threads, and otherwise <code class="methodname">getpid()</code>.
            </p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="id1675073"></a>Class</h3>
            </div>
          </div>
        </div>
        <p>
                    <a class="link" href="env.html" title="Chapter 5.  The DbEnv Handle">DbEnv</a>  
            </p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="id1675187"></a>See Also</h3>
            </div>
          </div>
        </div>
        <p>
                     <a class="xref" href="env.html#envlist" title="Database Environments and Related Methods">Database Environments and Related Methods</a> 
                </p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="envset_thread_count.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="env.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="envset_thread_id_string.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">DbEnv::set_thread_count() </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> DbEnv::set_thread_id_string()</td>
        </tr>
      </table>
    </div>
  </body>
</html>
